feat(windows): honour Windows "metered connection" flag for downloading updates by rc-swag · Pull Request #16099 · keymanapp/keyman

rc-swag · 2026-06-16T00:46:07Z

This adds a helper unit which uses the windows API to obtain a ConnectionProfile. This profile provides information about the connection status and connectivity statistics. This includes the connection costs, roaming, restricted etc. It also can check to see if background networking activity has been restricted.

Using the recommened example this commit combines these to determine if a network is metered. It also provides access to the background network being restricted.

There is a call that IsBackgroundUpdateAllowed that will return true if a background update is allowed.

This is then use in the Update State Machine and also by update pop up.
UpdateStateMachine
Before downloading IsBackgroundUpdateAllowed is called

Update Pop Up
This uses the IsMetered call and adds a warning if to the user who is wanting to Install Now.
This message would be better as a banner in the Update Configuration tab, rather than a delphi tab. This is the most efficent place to add the message for now.

Fixes: #13566

Build-bot: release:windows

User Testing

Mark connection as metered

For this we need to use windows setting to set the test machines network to metered. Right click the network connection icon in the Windows System tray and select network & internet settings Selected the connected work and the change the toggle for Metered connection to On

Windows 11

Windwos 10

TEST_RESTARTREQ_METERED

Use a keyboard update to test.

Install Keyman version attached to his PR
Download and install this older version of euro_latin
Make sure you have change the connected network to metered as explanined above.
Run Keyman
Go into the Keyman Configuration and the Update Tab
Press the check for updates button.
It should find an update for Euro Latin.
Press install updates ovbserve the warning is shown.

TEST_RESTARTREQ_NOT_METERED

This is to make sure a metered warning message is not present on non-metered connection.

Install Keyman version attached to his PR
Download and install this older version of euro_latin
Run Keyman.
Make sure you have change the connected network to metered OFF
Go into the Keyman Configuration and the Update Tab
Press the check for updates button.
It should find an update for Euro Latin.
Press install updates observe the metered warning is not shown.

TEST_NO_RESTARTREQ_METERED

This is to make sure a metered warning message is present but no other messages.

Install Keyman version attached to his PR
Download and install this older version of euro_latin
Do not run Keyman, if it has run sign in and out again.
Make sure you have change the connected network to metered OFF
Go into the Keyman Configuration and the Update Tab
Press the check for updates button.
It should find an update for Euro Latin.
Press install updates observe the metered warning is not shown.

TEST_NO_READY_TO_INSTALL_NOT_METERED

This is to make sure a metered connection message is not shown when
we already have the download and are just in the WaitingRestart State.

Install Keyman version attached to his PR
Download and install this older version of euro_latin
Make sure you have change the connected network to metered OFF
Go into the Keyman Configuration and the Update Tab
Press the check for updates button.
It should find an update for Euro Latin.
Close Configuration and the Keyman Splash screen if open.
Change the connected network to metered ON
1. Do not Run Keyman if Keyman has run you will need to sign out of the current windows session.
Start Keyman
A pop saying an update is ready observe the metered warning is not shown.

TEST_NO_BACKGROUND_UPDATE

Install Keyman version attached to his PR
Download and install this older version of sil_euro_latin.zip
Close Keyman an Keyman Configuration
Make sure you have change the connected network to metered as explanined above.
Open Regedit WinR type regedit
Go to the current user key update state found at (Computer\HKEY_CURRENT_USER\SOFTWARE\Keyman\Keyman Engine).
If required set the update state back to usIdle
Delete last update check time. This needs to be done otherwise it will stay in usIdle for 7 days.
Open Windows Explorer at "C:\Users"yourusername"\AppData\Local\Keyman\UpdateCache" folder.
Delete any *.kmp and *.exe files.
Open a command prompt and go to where kmshell is installed e.g c:\Program Files (x86)\Keyman\Keyman Desktop
run kmshell.exe -c This will run the configuration
Go to the Window Explorer window that is looking at the UpdateCache folder press F5 to refresh the window. No *.kmp or *.exe should appear as we are on metetered connection.

TEST_BACKGROUND_UPDATE

This is a regresion test.

Install Keyman version attached to his PR
Download and install this older version of sil_euro_latin.zip
Close Keyman an Keyman Configuration
Make sure you have change the connected network metered to OFF as explanined above.
Open Regedit WinR type regedit
Go to the current user key update state found at (Computer\HKEY_CURRENT_USER\SOFTWARE\Keyman\Keyman Engine).
If required set the update state back to usIdle
Delete last update check time. This needs to be done otherwise it will stay in usIdle for 7 days.
Open Windows Explorer at "C:\Users"yourusername"\AppData\Local\Keyman\UpdateCache" folder.
Delete any *.kmp and *.exe files.
Open a command prompt and go to where kmshell is installed e.g c:\Program Files (x86)\Keyman\Keyman Desktop
run kmshell.exe -c This will run the configuration
Go to the Window Explorer window that is looking at the UpdateCache folder press F5 to refresh the window. The sil_euro_latin.kmp should appear as we are not on a metered connection.

This adds a helper unit which uses the windows API to obtain a ConnectionProfile. This profile provides information about the connection status and connectivity statistics. This includes the connection costs, roaming, restricted etc. It also can check to see if background networking activity has been restricted. Using the recommened example this commit combines these to determine if a network is metered. It also provides access to the background network being restricted. Fixes: #13566

keymanapp-test-bot · 2026-06-16T00:46:12Z

User Test Results

Test specification and instructions

⬜ TEST_RESTARTREQ_METERED (OPEN)
⬜ TEST_RESTARTREQ_NOT_METERED (OPEN)
⬜ TEST_NO_RESTARTREQ_METERED (OPEN)
⬜ TEST_NO_READY_TO_INSTALL_NOT_METERED (OPEN)
✅ TEST_NO_BACKGROUND_UPDATE (PASSED) (notes)
✅ TEST_BACKGROUND_UPDATE (PASSED) (notes)

Results Template

# Test Results

* **TEST_RESTARTREQ_METERED (OPEN):** notes
* **TEST_RESTARTREQ_NOT_METERED (OPEN):** notes
* **TEST_NO_RESTARTREQ_METERED (OPEN):** notes
* **TEST_NO_READY_TO_INSTALL_NOT_METERED (OPEN):** notes

Test Artifacts

Windows

If the download has already occured before calling the pop up then there is no reason to warn about the metered connection.

Meng-Heng · 2026-06-22T08:20:06Z

Test Prerequisite

Windows 10 Bootcamp
Keyman version 19.0.248-alpha-test-16099
sil_euro_latin version 3.0.0

Test Results

TEST_WARNING_MESSAGE (PASSED):

The metered connection is set to on
Launch Keyman
Go into the Keyman Configuration -> the Update Tab
Press the check for updates button.
Update for Eurolatin (SIL) appears
Press install updates
Confirm -- The pop-up window does have the metered warning.

TEST_NO_WARNING_MESSAGE_PART1 (PASSED):

Launch Keyman
The metered connection is off
Go into the Keyman Configuration -> the Update Tab
Press the check for updates button
Update for Eurolatin (SIL) appears
Press install updates
Confirmed -- The pop-up window does not have the metered warning.

TEST_NO_WARNING_MESSAGE_PART2 (PASSED):

Launch Keyman
The metered connection stays off
Go into the Keyman Configuration -> the Update Tab
Press the check for updates button.
Update for Eurolatin (SIL) appears
Exit Keyman Configuration and the Keyman Splash screen from the tray
Start Keyman
Confirmed -- The pop-up window saying an update and does not have the metered warning

Note

I did not get the exact message as in the test requirement (see the image right above this note)

TEST_NO_BACKGROUND_UPDATE (PASSED):

Close Keyman and Keyman Configuration
The metered connection is set to on
Follow the instruction to delete last update check time in Computer\HKEY_CURRENT_USER\SOFTWARE\Keyman\Keyman Engine
Open Windows Explorer at "C:\Users\havm\AppData\Local\Keyman\UpdateCache" folder
Delete *.kmp file
Open a command prompt and go to c:\Program Files (x86)\Keyman\Keyman Desktop
Run kmshell.exe -c
The Keyman Configuration, Update tab opens up
Confirm – In Window Explorer window that is looking at the UpdateCache folder press, there is no *.kmp or *.exe appear as we are on metered connection.

TEST_BACKGROUND_UPDATE (PASSED):

Uninstall and reinstall Keyman
Launch Keyman and install the keyboard
Close Keyman and Keyman Configuration
The metered connection is set to off
Follow the instruction to delete last update check time in Computer\HKEY_CURRENT_USER\SOFTWARE\Keyman\Keyman Engine
Open Windows Explorer at "C:\Users\havm\AppData\Local\Keyman\UpdateCache" folder
The folder is empty
Open a command prompt and go to c:\Program Files (x86)\Keyman\Keyman Desktop
Run kmshell.exe -c This will run the configuration
Confirm – In the Window Explorer window that is looking at the UpdateCache folder, there is now a sil_euro_latin.kmp file as we are not on a metered connection.

Co-authored-by: Eberhard Beilharz <ermshiperete@users.noreply.github.com>

ermshiperete · 2026-06-23T10:02:02Z

+  if HasKeymanRun OR IsMetered then
  begin
-    frmStartInstallNow := TfrmStartInstall.Create(nil, true);
+    frmStartInstallNow := TfrmStartInstall.Create(nil, HasKeymanRun, IsMetered);


From devin.ai:

Contradictory dialog messages when IsMetered=True and HasKeymanRun=False in Update_ApplyNow

In UfrmMain.pas:831, when HasKeymanRun is False but IsMetered is True, the form is created with RestartRequired=False and ReadyToInstall=False (default). This causes FormCreate at Keyman.Configuration.UI.UfrmStartInstall.pas:72-73 to show S_Ready_To_Install ("An update to Keyman has been downloaded and is ready to install") while simultaneously displaying the metered warning S_Metered_Warning ("You're on a metered connection. Downloading now may incur data charges") at line 77. These messages directly contradict each other: one says the update has already been downloaded, while the other warns about downloading costs. Before this PR, this code path didn't exist — the old code only showed the dialog when HasKeymanRun was true, always passing RestartRequired=true, so S_Ready_To_Install was never displayed here.

Co-authored-by: Eberhard Beilharz <ermshiperete@users.noreply.github.com>

Keyman currenlty only supports Windows 10 and 11 so the exception was low risk. If it is not available we return false as metered connections werent possilble before this the functionality will be the consistent with those windows versions. i.e. always updating in the background

rc-swag · 2026-06-25T04:42:36Z

@Meng-Heng We need to test some scenarios again after my changes thanks.

mcdurdin

This change looks really solid.

One thing: I am not that comfortable with the UI of the dialog -- the red background is not consistent with styling of the rest of the app and I think we should use a standard Warning icon instead. Happy for that to be a follow-up PR.

mcdurdin · 2026-06-25T05:39:59Z

Can we use the modern file naming scheme:

Keyman.Configuration.Util.NetworkConnection.pas?

mcdurdin · 2026-06-25T05:43:49Z

+  Profile: IConnectionProfile;
+  CostLevel: IConnectionCost;


Do we need to initialize COM before these functions are called? If so, we should call that out in the docs

I'm not sure how to determine this.

https://blogs.embarcadero.com/a-tale-of-3-apis-vcl-integration-with-winapi-com-shellapi-winrt/

This is the first use of WinRT in the Keyman code. We should be moving towards it across the codebase. AFAICT, yes, we should initialize COM (which we already do) before calling these functions, but: https://microsoft.github.io/MIDI/kb/threading-and-initialization/ more to learn!

https://learn.microsoft.com/en-au/windows/win32/api/roapi/nf-roapi-roinitialize

mcdurdin · 2026-06-25T05:45:06Z

+      // If the WinRT network APIs are unavailable or throw (e.g. unusual
+      // Windows SKUs, containers, Network List Manager service stopped),
+      // treat the connection as non-metered so updates are not blocked.
+      Result := False;


Can we report errors on Sentry please? (Silent swallowing of the error is okay)

mcdurdin · 2026-06-25T05:45:11Z

+  except
+    on E: Exception do
+      // See IsMetered: default to not-restricted if the WinRT APIs throw.
+      Result := False;


Ditto Sentry

mcdurdin · 2026-06-25T05:51:54Z

+    icRestartRequiredMetered,
+    icRestartRequiredNotMetered,
+    icReadyToInstallNotMetered, // Metered warning never needed if ReadyToInstall
+    icNoInstallMessageMetered


I found this install case name confusing; is the following name accurate?

Suggested change

icNoInstallMessageMetered

icReadyToDownloadWarnMetered

I guess my confusion extends to the dialog box as well -- would it be possible for the dialog box to say something to clarify that a download is required, something like this?

The update has not yet been downloaded.
and
You're on a metered connection. Downloading now may incur data charges.

I don't like the name change suggested because it overlaps with the first case. I can see the confusion though with you suggested messages.

In thinking about the fact I have not got on to this issue # #13711 yet. The forground update is still confusing to the user especially if they are on a slow connection and click Check for Updates followed by Install Now on a slow connection it there will be no gui while it is downloading the update. Untill #13711 we can provide more information (at least in english, hopefully it gets translated will in the pop-up) I am worried though it maybe to much and confusing.

Scenarios.
Foreground Update Tab:
Messages that can be displayed in isolation or combination off.

Installing the update now will require a restar of your computer before you can use Keyman again. Update now anyway

The Update has not yet been downloaded Keyman Configuration will close and it will be downloaded in the background before installing
[The second part of this message in `` will be untill feat(windows): apply update now give progress if download still in progress #13711 is implemented then removed.]

You're on a metered connection. Downloading now may incur data charges.

OnBoot:
icReadyToInstallNotMetered
This is the true backroung update scenario. The update has downloaded in the background the user is starting Keyman, it has not been run we are just letting them know we are about to install the new version and giving them an option to cancel

An update to Keyman has been downloaded and is ready to install.

Now this code can be improved to actually use the StateMachine to check the state. It could be downloading or in updateavailable (if automatic updates are off).

Then for Update Tab
DownloadRequired && RestartRequired && Metered
-> icRestartRequiredMetered= show 1-3
DownloadRequired && RestartRequired && !Metered
-> icRestartRequiredNotMetered = show 1-2
DownloadRequired && !RestartRequired && !Metered
-> icDownloadRequired = show 2 (this is really now just informing about the pending silence :))
DownloadRequired && !RestartRequired && Metered
-> icNoInstallMessageMetered = show 2 & 3
!DownloadRequired && !RestartRequired && !Metered
-> no pop up required

Then for boot up

icReadyToInstallNotMetered = show 4.

Below I is the same as above but have renamed the enums for clarity with the additonal download message.

DownloadRequired && RestartRequired && Metered
-> icDownloadRestartMetered= show 1-3
DownloadRequired && RestartRequired && !Metered
-> icDownloadRestart = show 1-2
DownloadRequired && !RestartRequired && !Metered
-> icDownload = show 2 (this is really now just informing about the pending silence :))
DownloadRequired && !RestartRequired && Metered
-> icDownloadMetered = show 2 & 3
!DownloadRequired && !RestartRequired && !Metered
-> no pop up required

Then for boot up

icReadyToInstall = show 4.

Meng-Heng · 2026-06-25T09:24:50Z

@Meng-Heng We need to test some scenarios again after my changes thanks.

Noted with thanks, @rc-swag. I'll test this tomorrow.

Co-authored-by: Marc Durdin <marc@durdin.net>

rc-swag · 2026-07-07T23:24:59Z

This change looks really solid.

One thing: I am not that comfortable with the UI of the dialog -- the red background is not consistent with styling of the rest of the app and I think we should use a standard Warning icon instead. Happy for that to be a follow-up PR.

I will change the colour to yellow to match the No keyboards installed. a quick looks shows we currently don't have the yellow trianlge exclamantion mark icon in the repo. I might make that a quick follow up PR.

github-project-automation Bot added this to Keyman Jun 16, 2026

github-project-automation Bot moved this to Todo in Keyman Jun 16, 2026

keymanapp-test-bot Bot added the user-test-missing User tests have not yet been defined for the PR label Jun 16, 2026

rc-swag self-assigned this Jun 16, 2026

keymanapp-test-bot Bot added this to the A19S31 milestone Jun 16, 2026

github-actions Bot added windows/ windows/config/ feat labels Jun 16, 2026

keymanapp-test-bot Bot added has-user-test user-test-required User tests have not been completed and removed user-test-missing User tests have not yet been defined for the PR labels Jun 16, 2026

rc-swag added 2 commits June 16, 2026 15:58

Merge branch 'master' into feat/windows/13566/check-metered-connection

cc8b4d2

feat(windows): add intstall ready flag to pop up

94756fd

If the download has already occured before calling the pop up then there is no reason to warn about the metered connection.

rc-swag marked this pull request as ready for review June 17, 2026 03:57

rc-swag requested a review from mcdurdin June 17, 2026 03:58

rc-swag assigned Meng-Heng Jun 19, 2026

rc-swag requested review from ermshiperete and sgschantz June 19, 2026 04:25

rc-swag changed the title ~~feat(windows): add network connectivity tool~~ feat(windows): honour Windows "metered connection" flag for downloading updates Jun 19, 2026

keyman-server modified the milestones: A19S31, A19S32 Jun 22, 2026

Merge branch 'master' into feat/windows/13566/check-metered-connection

e92f01a

ermshiperete requested changes Jun 22, 2026

View reviewed changes

ermshiperete reviewed Jun 22, 2026

View reviewed changes

Comment thread windows/src/desktop/kmshell/main/UfrmMain.pas Outdated

Comment thread windows/src/desktop/kmshell/main/Keyman.Configuration.UI.UfrmStartInstall.pas Outdated

feat(windows): apply suggestions from code review

293f8ec

Co-authored-by: Eberhard Beilharz <ermshiperete@users.noreply.github.com>

keymanapp-test-bot Bot removed the user-test-required User tests have not been completed label Jun 23, 2026

github-actions Bot added the user-test-required User tests have not been completed label Jun 23, 2026

keymanapp-test-bot Bot removed the user-test-required User tests have not been completed label Jun 23, 2026

feat(windows): address review comments

5e26d5d

ermshiperete approved these changes Jun 23, 2026

View reviewed changes

rc-swag and others added 3 commits June 25, 2026 10:49

feat(windows): use enum to drive installfrm layout

3974f03

feat(windows): apply suggestions

85da9dc

Co-authored-by: Eberhard Beilharz <ermshiperete@users.noreply.github.com>

rc-swag requested a review from ermshiperete June 25, 2026 04:05

keymanapp-test-bot Bot added the user-test-required User tests have not been completed label Jun 25, 2026

mcdurdin requested changes Jun 25, 2026

View reviewed changes

rc-swag marked this pull request as draft June 25, 2026 09:49

rc-swag and others added 2 commits June 30, 2026 13:15

feat(windows): apply suggestions from code review

0bd7bf1

Co-authored-by: Marc Durdin <marc@durdin.net>

feat(windows): wrap network util in class

6009473

keyman-server modified the milestones: A19S32, A19S33 Jul 4, 2026

Uh oh!

Uh oh!

Conversation

rc-swag commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Testing

Mark connection as metered

TEST_RESTARTREQ_METERED

TEST_RESTARTREQ_NOT_METERED

TEST_NO_RESTARTREQ_METERED

TEST_NO_READY_TO_INSTALL_NOT_METERED

TEST_NO_BACKGROUND_UPDATE

TEST_BACKGROUND_UPDATE

Uh oh!

keymanapp-test-bot Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Test Results

Test Artifacts

Uh oh!

Meng-Heng commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Prerequisite

Test Results

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rc-swag commented Jun 25, 2026

Uh oh!

mcdurdin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rc-swag Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Meng-Heng commented Jun 25, 2026

Uh oh!

rc-swag commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

rc-swag commented Jun 16, 2026 •

edited

Loading

keymanapp-test-bot Bot commented Jun 16, 2026 •

edited

Loading

Meng-Heng commented Jun 22, 2026 •

edited

Loading

rc-swag Jul 7, 2026 •

edited

Loading